.\"
.\" Copyright (c) 1992, 1993, 1994, 1995
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	@(#)mount_newnfs.8	8.3 (Berkeley) 3/29/95
.\"
.Dd March 29, 1995
.Dt MOUNT_NEWNFS 8
.Os
.Sh NAME
.Nm mount_newnfs
.Nd mount nfs file systems
.Sh SYNOPSIS
.Nm mount_newnfs
.Op Fl 234ATUbcdilnsD
.Op Fl B Ar iothreadcnt
.Op Fl I Ar readdirsize
.Op Fl R Ar retrycnt
.Op Fl o Ar options
.Op Fl r Ar readsize
.Op Fl t Ar timeout
.Op Fl w Ar writesize
.Op Fl x Ar retrans
.Op Fl S Ar sec
.Op Fl P Ar princ
.Ar rhost:path node
.Sh DESCRIPTION
The
.Nm
command
calls the
.Xr mount 2
system call to prepare and graft a remote nfs file system (rhost:path)
on to the file system tree at the point
.Ar node.
This command is normally executed by
.Xr mount 8 .
It implements the mount protocol as described in
.%T "NFS: Network File System Protocol Specification" ,
RFC1094, Appendix A and
.%T "NFS Version 3 Protocol Specification" ,
RFC1813, Appendix I.
For NFS V4, is does an NFS V4 Compound RPC to look up the root directory,
as described in
.%T "Network File System (NFS) Version 4 Protocol" .
.Pp
The options are:
.Bl -tag -width indent
.It Fl 2
Use the NFS Version 2 protocol.
.It Fl 3
Use the NFS Version 3 protocol. The default is to try version 3 first, and
fall back to version 2 if the mount fails.
.It Fl 4
Use the NFS Version 4 protocol, which also implies using TCP transport.
.It Fl A
Allow NFSv4 ACLs to be inspected/set. This option should only be
used if the NFSv4 server supports full NFSv4 ACLs and not some subset
mapped to/from POSIX-1e Draft ACLs. Also, only use this option if
the client is kept connected to a network supporting the same
security association as the server is using, so that transient GUIDs are never
assigned.
See http://lists.apple.com/archives/Darwin-kernel/2008/Dec/msg00004.html for more information on this.
Note that a server will enforce any NFSv4 ACLs on it, regardless of this
option, which only affects the ability of the client to inspect/set them.
Also, most NFSv4 servers will generate 6 ACEs from the POSIX mode bits and
those ACEs will be alternating between Allow and Deny for Owner, Group and
Everyone. As such, you need to use "chmod +a#" and not "chmod +a" to
set ACEs and deletion of an ACL via "chmod -N" will result in an ACL
of these 6 ACEs.
This option should be considered experimental at this time, since there are
few NFSv4 servers with full NFSv4 ACL support and it has not been heavily
tested.
.It Fl B Ar iothreadcnt
Run iothreadcnt async I/O threads that do Read-ahead/Write-behind. The default
is 0, which seems to perform well for most LAN environments. You might see
better performance with the use of these, particularily in WAN environments.
(These were once called biods or nfsiods.)
If you do a non-automounted Kerberized mount, these will be children of
mount_newnfs, so that they can do upcalls to the gssd.
For automounted Kerberized mounts, they are kernel threads, since children
of mount_newnfs perturbed the automounter. This implies that these threads
cannot do upcalls to the gssd and may cause authentication problems in rare
cases. I would only set a non-zero iothreadcnt for automounted Kerberized
mounts if I really needed them for performance.
.It Fl I Ar readdirsize
Set the readdir read size to the specified value. The value should normally
be a multiple of DIRBLKSIZ that is <= the read size for the mount.
The default value for readdirsize will be whatever the server indicates for
NFSv3 and NFSv4. This should normally be sufficient. If you use
.Fl r
to set the readsize, you will probably want to set this to the same value.
.It Fl R Ar retrycnt
Set the retry count for doing the mount to the specified value.
.It Fl T
Use TCP transport instead of UDP.
This is recommended for servers that are not on the same LAN cable as
the client and is required for NFSv4.
.It Fl U
Force the mount protocol to use UDP transport, even for TCP NFS mounts.
(Necessary for some old BSD servers.)
.It Fl b
If an initial attempt to contact the server fails, fork off a child to keep
trying the mount in the background.
Useful for
.Xr fstab 5 ,
where the filesystem mount is not critical to multiuser operation.
.It Fl c
For UDP mount points, do not do a
.Xr connect 2 .
This must be used for servers that do not reply to requests from the
standard NFS port number 2049.  It may also be required for servers
with more than one IP address (only necessary if replies come from
an address other than the one specified in the mount request).
.It Fl d
Turn off the dynamic retransmit timeout estimator.
This may be useful for UDP mounts that exhibit high retry rates,
since it is possible that the dynamically estimated timeout interval is too
short.
.It Fl i
Make the mount interruptible, which implies that file system calls that
are delayed due to an unresponsive server will fail with EINTR when a
termination signal is posted for the process.
.It Fl l
Used with NFSV3 to specify that the \fBReaddirPlus\fR RPC should
be used.
This option reduces RPC traffic for cases such as
.Dq "ls -l" ,
but tends to flood the attribute and name caches with prefetched entries.
Try this option and see whether performance improves or degrades. Probably
most useful for client to server network interconnects with a large bandwidth
times delay product.
.It Fl D
This option forces all I/O to bypass the buffer cache and be done
directly to the server as RPCs. This is required for NFSv4 if the server
uses mandatory byte locking. It might also provide better performance when the client
is accessing large files sequentially.
.It Fl o Ar options
Options are specified with a
.Fl o
flag followed by a comma separated string of options.
See the
.Xr mount 8
man page for possible options and their meanings.
The following NFS specific option is also available:
.Bl -tag -width indent
.It port=portnumber
Use specified port number for NFS requests.
The default is to query the portmapper for the NFS port.
.It nfsv2
- Same as
.Fl 2 .
.It nfsv3
- Same as
.Fl 3 .
.It nfsv4
- Same as
.Fl 4 .
.It acl
- Same as
.Fl A .
.It tcp
- Same as
.Fl T .
.It mntudp
- Same as
.Fl U .
.It bg
- Same as
.Fl b .
.It conn
- Same as
.Fl c .
.It dumbtimr
- Same as
.Fl d .
.It intr
- Same as
.Fl i .
.It sec=authentication_type
- Same as
.Fl S .
.It rdirplus
- Same as
.Fl l .
.It soft
- Same as
.Fl s .
.It rsize=read_size_in_KBytes
- Same as
.Fl r .
.It wsize=write_size_in_KBytes
- Same as
.Fl w .
.It princ=principal_name
- Same as
.Fl P .
.It dio
- Same as
.Fl D .
.It allgssname
- Same as
.Fl n .
.It iothreadcnt=cnt
- Same as
.Fl B .
.It automounted
- Normally used by the automounter to indicate it is doing the mount. This will
result in the use of a kernel thread for doing Renew Ops on a Kerberized NFSv4 mount
point. As such, it can't do upcalls to the gssd and will fail on an inactive
mount point. Hopefully the automounter will dismount the file system before
this becomes a problem, but there is no guarantee. (If you want NFSv4 Kerberized
mount points to keep working beyond the time limit of your TGT, you should do
them via command line and not use the automounter.)
.El
.It Fl r Ar readsize
Set the read data size to the specified value, specified in Kilobytes.
This should be used for UDP mounts when the
.Dq "fragments dropped due to timeout"
value is getting large while actively using a mount point.
(Use
.Xr netstat 1
with the
.Fl s
option to see what the
.Dq "fragments dropped due to timeout"
value is.)
For NFSv3 and NFSv4, the default is the preferred value specified by
the server and should be sufficient for most mounts using TCP.
See the
.Fl w
option as well.
.It Fl s
A soft mount, which implies that file system calls will fail
after \fBRetry\fR round trip timeout intervals.
Not recommended and highly not recommended for NFSv4 mounts.
.It Fl t Ar timeout
Set the initial retransmit timeout to the specified value.
May be useful for fine tuning UDP mounts over internetworks
with high packet loss rates or an overloaded server.
Try increasing the interval if
.Xr newnfsstat 1
shows high retransmit rates while the file system is active or reducing the
value if there is a low retransmit rate but long response delay observed.
(Normally, the
.Fl d
option should be specified when using this option to manually
tune the timeout
interval.)
.It Fl w Ar writesize
Set the write data size to the specified value, specified in Kilobytes.
Ditto the comments w.r.t. the
.Fl r
option, but using the
.Dq "fragments dropped due to timeout"
value on the server instead of the client.
Note that both the
.Fl r
and
.Fl w
options should only be used as a last ditch effort at improving performance
when mounting servers that do not support TCP mounts.
.It Fl x Ar retrans
Set the retransmit timeout count for soft mounts to the specified value.
.It Fl S Ar sec
Set the authentication mechanism for the mount point. The default is
"sys", which refers to AUTH_SYS and simply sends <uid, gid, ...> out on the wire in clear text.
Alternatives are "krb5", "krb5i" and "krb5p", which all use KerberosV for
user authentication. The "krb5i" variant also provides integrity checking of the RPC data
using an encrypted checksum. "krb5p" goes a step further and DES encrypts
all RPC data on the wire. (All of the KerberosV vaiants use RPCSEC_GSS authentication
handling.)
.Pp
There is no well defined rules for mapping between KerberosV principal
names and <uid, gid, ...> credentials. My
.Xr gssd 8
daemon simply strips off @<YOUR.REALM> and looks the name up in the
.Xr passwd 5
database via
.Xr getpwnam 3 .
It then uses the <uid, gid, ...> list for this user.
.It Fl P Ar princ
Sets the principal name to be used while mounting when "krb5[ip]"
security is specified. This principal name would normally
be a host based name, such as root@<client-hostname.domain>.
If you do not specify this option, all RPCs are done using
the credentials for the uid that did the mount, including
the state related ones, such as SetClientID.
There must be a corresponding KerberosV
principal name (root/<client-hostname.domain>@<YOUR>REALM>,
nfs/<client-hostname.domain>@<YOUR.REALM> or
host/<client-hostname.domain>@<YOUR.REALM>) in a keytab entry on the
client. This principal is normally mapped to "nobody" on the server,
but is allowed to do operations like Renew leases, for NFSv4.
.Pp
This option can never be used for Mac OS X (Leopard).
.It Fl n
This option is used with a krb5[ip] mount to tell the client to always use
the host based principal authentication, instead of one based on the
effective uid. This might be useful for mounts of system stuff, such as
a read-only /usr/local/bin.
This option requires the
.Fl P
option be used, to set the principal name.
.El
.Sh SEE ALSO
.Xr mount 2 ,
.Xr unmount 2 ,
.Xr fstab 5 ,
.Xr mount 8
.Sh BUGS
Due to the way that Sun RPC is implemented on top of UDP (unreliable datagram)
transport, tuning such mounts is really a black art that can only be expected
to have limited success.
For clients mounting servers that are not on the same
LAN cable or that tend to be overloaded,
TCP transport is strongly recommended.
